qsection Introduction {{The jhelp application was developed as a tool for displaying online manuals for Tk¡based applications. (Of course, there's no reason it can't be used for other kinds of files as well.) The help files it displays consist of one or more sections, and you can view the sections in any order.
The jhelp help viewer is distributed as part of the jstools package.
jhelp is intended to be invoked automatically by Tk¡based applications, but you can also invoke it yourself from the command line by typing `jhelp topic', where topic is the name of a jhelp help file. If the requested file can't be found, an alert box will tell you so.
If you don't specify a topic, you'll be prompted to choose one from a list of available help files.}} {{{sel {}} {hilight {}} {xref-topic {}} {xref-section {}} {j:rt:rm {1.0 2.1 2.12 4.0 4.5 4.141 4.152 4.161 4.166 4.184 4.189 6.23 6.28 6.99}} {j:rt:it {2.7 2.12 4.147 4.152 4.161 4.166 6.23 6.28}} {j:rt:bf {}} {j:rt:bi {}} {j:rt:tt {2.1 2.7 4.0 4.5 4.141 4.147 4.184 4.189}} {j:rt:hl {}} {TOPIC:jedit {}} {{SECTION:Customising the Editor} {}} {TOPIC:jbrowser {}}} {{matchend 6.99} {abbrevstart 6.99} {del_from 6.99} {insert 1.0} {matchstart 6.99} {del_to 6.99} {anchor 4.186} {current 6.99}}}
qsection {Using the Help Viewer} {{When it starts (and successfully reads in a help file), jhelp displays the first section.
Buttons
There are three buttons at the bottom of the help window:
The `Done' button closes the window and quits the help viewer. (It's the same as choosing `Quit' from the `Help' menu.)
The `Next' button lets you view the next section. It's disabled if you're currently viewing the last section in the help file.
The `Back' button lets you go back to the previous section. It's disabled if you're currently viewing the first section in the help file.
The Sections Menu
The sections are listed under the `Sections' menu, and you can go to a particular section by choosing it from the menu. The section you choose will be displayed in the main text area of the window. If it is too long to fit in the window all at once, you can use the scrollbar to scroll through the whole section. (You can also scan through the text by dragging with the middle mouse button.) When you're done, you can quit either by clicking the big `Done' button at the bottom of the window, or by choosing `Quit' from the `Help' menu.
The Topics Menu
You can choose `Select a Topic...' from the `Topics' menu to choose a new help file from a list of available topics.
The Help Menu
You can get help about the jhelp application itself - this file - by choosing `Help with Help' from the `Help' menu, and `About Help' under the `Help' menu displays an information panel about the program, with copyright information and my email address.
`Issue Tcl Command...' brings up a panel that prompts you for a Tcl command to be executed. This is mainly useful for debugging.
There are also preferences panels, described under Preferences, which you can get by choosing `Global Preferences...' or `Help Viewer Preferences...' under the `Help' menu.}} {{{sel {}} {hilight {}} {xref-topic {}} {xref-section {23.51 23.62}} {j:rt:rm {1.0 1.56 1.61 3.0 4.0 12.0 12.17 15.0 15.15 18.0 18.13 19.27 19.32 23.51 23.62 23.172}} {j:rt:it {}} {j:rt:bf {}} {j:rt:bi {23.51 23.62}} {j:rt:tt {1.56 1.61 19.27 19.32}} {j:rt:hl {3.0 4.0 12.0 12.17 15.0 15.15 18.0 18.13}} {TOPIC:jedit {}} {{SECTION:Customising the Editor} {}} {TOPIC:jbrowser {}} {SECTION:Preferences {23.51 23.62}}} {{matchend 23.113} {abbrevstart 23.148} {del_from 23.172} {insert 1.0} {matchstart 23.102} {del_to 11.0} {anchor 23.150} {current 10.72}}}
qsection {Keyboard Shortcuts} {{Some commands have keyboard shortcuts, which appear in brackets beside the menu entry. To invoke a keyboard shortcut, hold down whatever the Meta key is on your keyboard, and press the key in brackets. (The Meta key is labelled differently on different keyboards; it may be marked `Meta', `Alt', `Mod', or something else. On current Sun keyboards, it's marked with a little diamond.) You may also need to hold down the Shift key; for instance, Meta-l is `Select a Topic...', but Meta-Shift-T is `Issue Tcl Command...'.}} {{{sel {}} {hilight {}} {xref-topic {}} {xref-section {}} {j:rt:rm {1.0 1.142 1.146 1.208 1.212 1.422 1.427 1.447 1.453 1.482 1.494 1.521}} {j:rt:it {}} {j:rt:bf {1.142 1.146 1.208 1.212 1.422 1.427 1.447 1.453 1.482 1.494}} {j:rt:bi {}} {j:rt:tt {}} {j:rt:hl {}} {TOPIC:jedit {}} {{SECTION:Customising the Editor} {}} {TOPIC:jbrowser {}} {SECTION:Preferences {}}} {{matchend 1.521} {abbrevstart 1.521} {del_from 1.521} {insert 1.0} {matchstart 1.521} {del_to 1.521} {anchor 1.521} {current 1.521}}}
qsection Preferences {{Two different preference panels, available under the `Help' menu, allow you to change the look¡and¡feel of the help viewer, and a little bit of its behaviour.
The Global Preferences panel lets you set preferences that apply to all the jstools applications (such as jbrowser and jedit), and any other Tk applications that choose to honour them. The Help Viewer Preferences panel lets you set preferences that only apply to the jhelp application itself.
On both of the panels, clicking `Save' will save the currently¡displayed preferences, so they'll be used the next time you start up jhelp, while clicking `Done' won't save them for future use, but will apply them to your current editing session.
Global Preferences...
If `Auto¡position dialogue boxes' is selected, then the help viewer will attempt to centre dialogue boxes (like the Preferences panel itself) on the screen. Otherwise it will let your window manager position them (and your window manager may ask you to choose a position for them).
If `Confirm actions' is selected, the help viewer will ask for confirmation before certain actions, such as quitting or overwriting an existing file. This is the default, but you will no doubt quickly become annoyed with it. You are welcome to turn it off.
If `Strict Motif Emulation' is not selected, user¡interface components such as buttons and scrollbars will highlight when the mouse pointer is moved over them to indicate they are active. If it is selected, they will not change colour. This preference doesn't take effect until the next time an application is run.
If `Scrollbars on left' is selected, scrollbars will be put to the left of the objects (normally text widgets or listboxes) they control; otherwise they'll be put to the right. This preference doesn't take effect until the next time a window with a scrollbar is created (i.e., windows that are already on the screen won't have their scrollbars moved).
The next three radio buttons let you select what kind of keyboard bindings you want. `Basic bindings' gives you a very basic interface, which supports the arrow keys, the mouse, the Home, End, Next, and Prior (or PageUp and PageDown) keys if your keyboard has them, and not much else. `Emacs bindings' gives you keyboard bindings modelled after the default keyboard commands of the Emacs editor, including the use of Control-u or Escape+number for repetition. `vi bindings' will give you keyboard bindings modelled after those of the vi editor, but it isn't yet available in this version.
Note that you can also customise your keyboard bindings by putting Tcl commands to set Text and Entry bindings in a file called ~/.textbindings.tcl. For more information on this see the section Customising the Help Viewer.
The `Printer:' field lets you type in the name of your printer. This is used for the `Print...' command.
Global preferences are saved in the file ~/.tk/defaults.
Help Viewer Preferences...
The Help Viewer Preferences panel lets you customise the appearance of the big text area that contains the help file. It lets you set size of the window, the colours used to display the text, the width of the raised border drawn around selected text, and the width of the blank border around the entire text window.
The `Width:' and `Height:' fields let you change the width (in columns) and height (in characters) of the help viewer. Because the help viewer can display fonts of various sizes and the characters aren't necessarily all the same width, these figures are approximate.
The buttons labelled `RGB' let you select a colour by manipulating sliders that represent the individual red, green, and blue components of the colour you're choosing. The buttons labelled `Name' let you select a colour by name, from the list of colours known on your system.
(Note: If the name of the colour database on your system isn't /usr/lib/X11/rgb.txt, then the `Name' colour buttons won't list all the colours available.)
Help viewer preferences are saved in the file ~/.tk/jhelp-defaults.
qsection {About Help Files} {{jhelp looks for help files in /usr/local/lib/tk/jhelp (that's the directory jhelp in the standard Tk library directory), in the directories tk/jhelp or .tk/jhelp in your home directory if they exist, and in the current directory. Help files end in the extension `.jhelp', so for the command `jhelp jlibrary.tcl' to succeed, there must be a file named jlibrary.tcl.jhelp in one of those three directories.
To see what help files are available, choose `Select a Topic...' from the `Topics' menu.
The help files are in an unusual format, but they are ASCII text files, and in a pinch you can read them directly.
qsection {Implementation Notes} {{The jhelp application works by defining a number of Tcl procedures: section, rm, it, cr, and so forth. The procedures which display text, like rm, each take one argument, the text to be displayed in that font. (These procedures are defined in the jrichtext.tcl library.) The whole thing is driven by the section procedure, which takes two arguments: the name of the section and the Tcl commands to produce the text of that section. It creates a new menu entry under `Sections' with the name specified by the first argument, which executes the second argument (along with some supporting code) as a Tcl procedure.
Help files which are automatically generated by jedit's help mode use the qsection procedure instead of section. Instead of commands for formatting text in particular styles, the arguments to qsection include the entire text as a single chunk, and information about which ranges of characters are in particular styles.
Because a help file is a set of commands (albeit specially¡defined commands) in the Tcl language, you can do a lot more in a help file than might at first be apparent. For instance, a help file could create new jhelp menus, or change the user interface in other ways. Also, the help text doesn't have to be formatted exactly as described under Writing Help Files. However, for legibility, and in order to insure compatibility with future tools, help files that really are intended as help files should try to conform to the rules set out in that section.
Future Plans
One `future tool' I have in mind is a tool that will take jhelp help files and, by redefining the basic procedures, turn them into various other formats, such as man pages, TeX source, or PostScript.}} {{{sel {}} {hilight {}} {xref-topic {1.249 1.262 3.48 3.53}} {xref-section {5.345 5.363}} {j:rt:rm {1.0 1.4 1.9 1.68 1.75 1.77 1.79 1.81 1.83 1.85 1.87 1.144 1.146 1.249 1.262 1.307 1.314 3.48 3.53 3.74 3.82 3.104 3.111 3.193 3.201 5.212 5.217 5.345 5.363 7.0 7.12 8.58 8.63 8.199}} {j:rt:it {}} {j:rt:bf {}} {j:rt:bi {5.345 5.363}} {j:rt:tt {1.4 1.9 1.68 1.75 1.77 1.79 1.81 1.83 1.85 1.87 1.144 1.146 1.249 1.262 1.307 1.314 3.48 3.53 3.74 3.82 3.104 3.111 3.193 3.201 5.212 5.217 8.58 8.63}} {j:rt:hl {7.0 7.12}} {TOPIC:jedit {3.48 3.53}} {{SECTION:Customising the Editor} {}} {TOPIC:jbrowser {}} {SECTION:Preferences {}} {{SECTION:Writing Help Files} {5.345 5.363}} {TOPIC:jrichtext.tcl {1.249 1.262}}} {{matchend 8.199} {abbrevstart 3.298} {del_from 8.199} {insert 1.0} {matchstart 8.199} {del_to 8.199} {anchor 3.196} {current 3.238}}}
qsection {Customising Help} {{The jhelp application will read in the file .tk/jhelprc.tcl in your home directory if it exists. You can customise the user interface by putting Tcl code in that file.
(You can also do some customisation through the preferences panels, described under Preferences. Also, jhelp reads your .textbindings.tcl file if you have one, although that isn't too useful in a help viewer.)
If jhelp was installed properly at your site, the directory /usr/local/lib/tk/jhelp/samples should contain some example files which you can copy and rename appropriately and modify. You may also find it useful to look at the jhelp script itself, and for information about Tcl syntax you should consult the Tcl man page.}} {{{sel {}} {hilight {}} {xref-topic {}} {xref-section {3.84 3.95}} {j:rt:rm {1.0 1.4 1.9 1.44 1.59 3.84 3.95 3.104 3.109 3.121 3.138 5.3 5.8 5.60 5.91 5.226 5.231 5.320}} {j:rt:it {}} {j:rt:bf {1.44 1.59 3.121 3.138 5.60 5.91}} {j:rt:bi {3.84 3.95}} {j:rt:tt {1.4 1.9 3.104 3.109 5.3 5.8 5.226 5.231}} {j:rt:hl {}} {TOPIC:jedit {}} {{SECTION:Customising the Editor} {}} {TOPIC:jbrowser {}} {SECTION:Preferences {3.84 3.95}} {{SECTION:Writing Help Files} {}} {TOPIC:jrichtext.tcl {}}} {{matchend 5.320} {abbrevstart 3.78} {del_from 5.320} {insert 1.0} {matchstart 5.320} {del_to 5.320} {anchor 1.6} {current 1.0}}}
qsection {Changes, Bugs, and Future Directions} {{Future Directions
Support for generating hardcopy is sorely needed.
It would be useful to allow help files to include other help files, or parts of them.
I want to add support for specifying fonts to the Help Viewer Preferences panel.
There should be a Find panel.
You should be able to nest sections arbitrarily - i.e., the help viewer should support arbitrary levels of subsections.
Hypertext links should be much more versatile - you should be able to go to locations within a section. It might be nice to provide hypertext links for man pages as well.
In the long term, I want to go to a more standard format like TeXinfo or HTML for help files.
Known Bugs and Misfeatures
None that I can think of, but then, it's not a very ambitious application.
Changes since Version 3.2/1.0
The following changes have been made since version 3.2/1.0 of help.tk:
* The extension for help files has been changed. Also, jhelp is now much less forgiving about the extensions on help files.
* The name has been changed to jhelp, to avoid having a period in the X application name and to avoid potential conflict with other applications.
* Support for a new help file format based on the qsection procedure has been added. This was done in order to make it easier to write a help¡text editing mode for jedit. (It's also noticeably faster.) The new format also supports rudimentary hypertext links.
* The `Topics' menu is new, as is that fact that jhelp will prompt you rather than complaining if you don't specify a help file on the command line.
* The `Back' and `Next' buttons are new.
* The preferences mechanism has been changed, and the preferences panel has been split in two.
